/*
 * Copyright 2002-2010 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.support;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;

/**
 * Extension to the standard {@link BeanFactoryPostProcessor} SPI, allowing for
 * the registration of further bean definitions <i>before</i> regular
 * BeanFactoryPostProcessor detection kicks in. In particular,
 * BeanDefinitionRegistryPostProcessor may register further bean definitions
 * which in turn define BeanFactoryPostProcessor instances.
 *
 * 对标准的 {@link BeanFactoryPostProcessor} SPI（Service Provider Interface（服务提供者接口）） 的扩展，
 * 允许在常规 BeanFactoryPostProcessor 检测之前注册额外的 BeanDefinition。
 * 特别是，BeanDefinitionRegistryPostProcessor 可以注册额外的 BeanDefinition，
 * 这些 BeanDefinition 可能会定义新的 BeanFactoryPostProcessor 实例。
 *
 * 核心功能：
 * 1. 提供在 Spring 容器初始化阶段注册额外 BeanDefinition 的能力。
 * 2. 允许动态增加 BeanFactoryPostProcessor 或普通 Bean 的定义。
 *
 * 主要逻辑流程：
 * 1. 容器启动时扫描所有 BeanFactoryPostProcessor。
 * 2. 区分普通 BeanFactoryPostProcessor 和 BeanDefinitionRegistryPostProcessor。
 * 3. 对 BDRPP 调用 postProcessBeanDefinitionRegistry() 方法，注册新的 BeanDefinition。
 * 4. 容器在后续阶段继续调用 postProcessBeanFactory() 完成后置处理。
 *
 * 框架作用：
 * - 提供在 Bean 实例化前扩展 Bean 定义的入口。
 * - 被 Spring 核心类 PostProcessorRegistrationDelegate 调度。
 * - 支撑 ConfigurationClassPostProcessor 等关键组件的注册逻辑。
 *
 * @author Juergen Hoeller
 * @since 3.0.1
 * @see org.springframework.context.annotation.ConfigurationClassPostProcessor
 */
public interface BeanDefinitionRegistryPostProcessor extends BeanFactoryPostProcessor {

	/**
	 * Modify the application context's internal bean definition registry after its
	 * standard initialization. All regular bean definitions will have been loaded,
	 * but no beans will have been instantiated yet. This allows for adding further
	 * bean definitions before the next post-processing phase kicks in.
	 *
	 * 在应用上下文标准初始化之后，修改内部的 BeanDefinitionRegistry。
	 * 所有常规的 BeanDefinition 已经被加载，但 Bean 实例尚未创建。
	 * 这使得在下一阶段的 BeanFactory 后置处理开始前，可以注册额外的 BeanDefinition。
	 *
	 * 核心功能：
	 * - 提供在 Bean 实例化前操作 BeanDefinitionRegistry 的扩展点。
	 *
	 * 主要逻辑流程：
	 * 1. 容器初始化 DefaultListableBeanFactory。
	 * 2. 通过 PostProcessorRegistrationDelegate 找到所有 BDRPP。
	 * 3. 依次调用每个 BDRPP 的 postProcessBeanDefinitionRegistry()。
	 * 4. BDRPP 可以调用 registry.registerBeanDefinition() 注册新的 BeanDefinition。
	 * 5. 新注册的 BeanDefinition 会在后续 BeanFactoryPostProcessor 阶段被处理。
	 *
	 * 框架作用：
	 * - 支撑 ConfigurationClassPostProcessor 注册 @Configuration 类及 @Bean 方法。
	 * - 保证动态 BeanDefinition 可以被容器识别并实例化。
	 *
	 * @param registry the bean definition registry used by the application context
	 *                 应用上下文使用的 BeanDefinitionRegistry
	 * @throws org.springframework.beans.BeansException in case of errors
	 *                                        发生错误时抛出 BeansException
	 */
	void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException;

}
